﻿// --------------------------------------------------------------------------------------------------------------------
// <copyright file="IStorage.cs" company="XamlNinja">
//   2011 Richard Griffin and Ollie Riches
// </copyright>
// <summary>
//   The i storage.
// </summary>
// --------------------------------------------------------------------------------------------------------------------

namespace WP7Contrib.Services.Storage
{
    using System;
    using System.Linq.Expressions;

    /// <summary>
    /// Interface defining the storage API.
    /// </summary>
    public interface IStorage : IDisposable
    {
        /// <summary>
        /// Gets the name context for the current storage.
        /// </summary>
        string Name { get; }

        /// <summary>
        /// Reads a value from storage using the name of an existing name value pair.
        /// </summary>
        /// <param name="name">
        /// The name of the name value pair.
        /// </param>
        /// <typeparam name="T">
        /// The type of the value of the name value pair.
        /// </typeparam>
        /// <returns>
        /// Returns the value or null.
        /// </returns>
        T Read<T>(string name);

        /// <summary>
        /// Reads a value from storage using the name of an existing name value pair.
        /// </summary>
        /// <param name="expression">
        /// Expression which name represents the name of the name value pair.
        /// </param>
        /// <typeparam name="T">
        /// The type of the value of the name value pair.
        /// </typeparam>
        /// <returns>
        /// Returns the value or null.
        /// </returns>
        T Read<T>(Expression<Func<object>> expression);

        /// <summary>
        /// Writes a value to storage.
        /// </summary>
        /// <param name="name">
        /// The name of the name value pair.
        /// </param>
        /// <param name="value">
        /// The value of the name value pair.
        /// </param>
        /// <typeparam name="T">
        /// The type of the value of the name value pair.
        /// </typeparam>
        /// <returns>
        /// Returns the instance of the storage - fluent interface style.
        /// </returns>
        IStorage Write<T>(string name, T value);

        /// <summary>
        /// Writes a value to storage.
        /// </summary>
        /// <param name="expression">
        /// Expression which name represents the name of the name value pair.
        /// </param>
        /// <param name="value">
        /// The value of the name value pair.
        /// </param>
        /// <typeparam name="T">
        /// The type of the value of the name value pair.
        /// </typeparam>
        /// <returns>
        /// Returns the instance of the storage - fluent interface style.
        /// </returns>
        IStorage Write<T>(Expression<Func<object>> expression, T value);

        /// <summary>
        /// Flushes any pending storage requests.
        /// </summary>
        /// <returns>
        /// Returns the instance of the storage - fluent interface style.
        /// </returns>
        IStorage Flush();

        /// <summary>
        /// Clears the storage.
        /// </summary>
        /// <returns>
        /// Returns the instance of the storage - fluent interface style.
        /// </returns>
        IStorage Clear();
    }
}